home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / util / Set.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  11.2 KB  |  281 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Set.java    1.18 98/09/30
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * A collection that contains no duplicate elements.  More formally, sets
  19.  * contain no pair of elements <code>e1</code> and <code>e2</code> such that
  20.  * <code>e1.equals(e2)</code>, and at most one null element.  As implied by
  21.  * its name, this interface models the mathematical <i>set</i> abstraction.<p>
  22.  *
  23.  * The <tt>Set</tt> interface places additional stipulations, beyond those
  24.  * inherited from the <tt>Collection</tt> interface, on the contracts of all
  25.  * constructors and on the contracts of the <tt>add</tt>, <tt>equals</tt> and
  26.  * <tt>hashCode</tt> methods.  Declarations for other inherited methods are
  27.  * also included here for convenience.  (The specifications accompanying these
  28.  * declarations have been tailored to the <tt>Set</tt> interface, but they do
  29.  * not contain any additional stipulations.)<p>
  30.  *
  31.  * The additional stipulation on constructors is, not surprisingly,
  32.  * that all constructors must create a set that contains no duplicate elements
  33.  * (as defined above).<p>
  34.  *
  35.  * Note: Great care must be exercised if mutable objects are used as set
  36.  * elements.  The behavior of a set is not specified if the value of an object
  37.  * is changed in a manner that affects equals comparisons while the object is
  38.  * an element in the set.  A special case of this prohibition is that it is
  39.  * not permissible for a set to contain itself as an element.
  40.  *
  41.  * @author  Josh Bloch
  42.  * @version 1.18 09/30/98
  43.  * @see Collection
  44.  * @see List
  45.  * @see SortedSet
  46.  * @see HashSet
  47.  * @see TreeSet
  48.  * @see AbstractSet
  49.  * @see Collections#singleton(java.lang.Object)
  50.  * @see Collections#EMPTY_SET
  51.  * @since JDK1.2
  52.  */
  53.  
  54. public interface Set extends Collection {
  55.     // Query Operations
  56.  
  57.     /**
  58.      * Returns the number of elements in this set (its cardinality).  If this
  59.      * set contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
  60.      * <tt>Integer.MAX_VALUE</tt>.
  61.      *
  62.      * @return the number of elements in this set (its cardinality).
  63.      */
  64.     int size();
  65.  
  66.     /**
  67.      * Returns <tt>true</tt> if this set contains no elements.
  68.      *
  69.      * @return <tt>true</tt> if this set contains no elements.
  70.      */
  71.     boolean isEmpty();
  72.  
  73.     /**
  74.      * Returns <tt>true</tt> if this set contains the specified element.  More
  75.      * formally, returns <tt>true</tt> if and only if this set contains an
  76.      * element <code>e</code> such that <code>(o==null ? e==null :
  77.      * o.equals(e))</code>.
  78.      *
  79.      * @return <tt>true</tt> if this set contains the specified element.
  80.      */
  81.     boolean contains(Object o);
  82.  
  83.     /**
  84.      * Returns an iterator over the elements in this set.  The elements are
  85.      * returned in no particular order (unless this set is an instance of some
  86.      * class that provides a guarantee).
  87.      *
  88.      * @return an iterator over the elements in this set.
  89.      */
  90.     Iterator iterator();
  91.  
  92.     /**
  93.      * Returns an array containing all of the elements in this set.
  94.      * Obeys the general contract of the <tt>Collection.toArray</tt> method.
  95.      *
  96.      * @return an array containing all of the elements in this set.
  97.      */
  98.     Object[] toArray();
  99.  
  100.     /**
  101.      * Returns an array containing all of the elements in this set whose
  102.      * runtime type is that of the specified array.  Obeys the general
  103.      * contract of the <tt>Collection.toArray(Object[])</tt> method.
  104.      *
  105.      * @param a the array into which the elements of this set are to
  106.      *        be stored, if it is big enough; otherwise, a new array of the
  107.      *         same runtime type is allocated for this purpose.
  108.      * @return an array containing the elements of this set.
  109.      * @throws    ArrayStoreException the runtime type of a is not a supertype
  110.      * of the runtime type of every element in this set.
  111.      */
  112.     Object[] toArray(Object a[]);
  113.  
  114.  
  115.     // Modification Operations
  116.  
  117.     /**
  118.      * Adds the specified element to this set if it is not already present
  119.      * (optional operation).  More formally, adds the specified element,
  120.      * <code>o</code>, to this set if this set contains no element
  121.      * <code>e</code> such that <code>(o==null ? e==null :
  122.      * o.equals(e))</code>.  If this set already contains the specified
  123.      * element, the call leaves this set unchanged and returns <tt>false</tt>.
  124.      * In combination with the restriction on constructors, this ensures that
  125.      * sets never contain duplicate elements.<p>
  126.      *
  127.      * The stipulation above does not imply that sets must accept all
  128.      * elements; sets may refuse to add any particular element, including
  129.      * <tt>null</tt>, and throwing an exception, as described in the
  130.      * specification for <tt>Collection.add</tt>.  Individual set
  131.      * implementations should clearly document any restrictions on the the
  132.      * elements that they may contain.
  133.      *
  134.      * @param o element to be added to this set.
  135.      * @return <tt>true</tt> if this set did not already contain the specified
  136.      *         element.
  137.      * 
  138.      * @throws UnsupportedOperationException if the <tt>add</tt> method is not
  139.      *            supported by this set.
  140.      * @throws ClassCastException if the class of the specified element
  141.      *            prevents it from being added to this set.
  142.      * @throws IllegalArgumentException if some aspect of this element
  143.      *         prevents it from being added to this set.
  144.      */
  145.     boolean add(Object o);
  146.  
  147.  
  148.     /**
  149.      * Removes the specified element from this set if it is present (optional
  150.      * operation).  More formally, removes an element <code>e</code> such that
  151.      * <code>(o==null ?  e==null : o.equals(e))</code>, if the set contains
  152.      * such an element.  Returns <tt>true</tt> if the set contained the
  153.      * specified element (or equivalently, if the set changed as a result of
  154.      * the call).  (The set will not contain the specified element once the
  155.      * call returns.)
  156.      *
  157.      * @param o object to be removed from this set, if present.
  158.      * @return true if the set contained the specified element.
  159.      * @throws UnsupportedOperationException if the <tt>remove</tt> method is
  160.      *         not supported by this set.
  161.      */
  162.     boolean remove(Object o);
  163.  
  164.  
  165.     // Bulk Operations
  166.  
  167.     /**
  168.      * Returns <tt>true</tt> if this set contains all of the elements of the
  169.      * specified collection.  If the specified collection is also a set, this
  170.      * method returns <tt>true</tt> if it is a <i>subset</i> of this set.
  171.      *
  172.      * @param c collection to be checked for containment in this set.
  173.      * @return <tt>true</tt> if this set contains all of the elements of the
  174.      *            specified collection.
  175.      */
  176.     boolean containsAll(Collection c);
  177.  
  178.     /**
  179.      * Adds all of the elements in the specified collection to this set if
  180.      * they're not already present (optional operation).  If the specified
  181.      * collection is also a set, the <tt>addAll</tt> operation effectively
  182.      * modifies this set so that its value is the <i>union</i> of the two
  183.      * sets.  The behavior of this operation is unspecified if the specified
  184.      * collection is modified while the operation is in progress.
  185.      *
  186.      * @param c collection whose elements are to be added to this set.
  187.      * @return <tt>true</tt> if this set changed as a result of the call.
  188.      * 
  189.      * @throws UnsupportedOperationException if the <tt>addAll</tt> method is
  190.      *           not supported by this set.
  191.      * @throws ClassCastException if the class of some element of the
  192.      *           specified collection prevents it from being added to this
  193.      *           set.
  194.      * @throws IllegalArgumentException if some aspect of some element of the
  195.      *          specified collection prevents it from being added to this
  196.      *          set.
  197.      * @see #add(Object)
  198.      */
  199.     boolean addAll(Collection c);
  200.  
  201.     /**
  202.      * Retains only the elements in this set that are contained in the
  203.      * specified collection (optional operation).  In other words, removes
  204.      * from this set all of its elements that are not contained in the
  205.      * specified collection.  If the specified collection is also a set, this
  206.      * operation effectively modifies this set so that its value is the
  207.      * <i>intersection</i> of the two sets.
  208.      *
  209.      * @param c collection that defines which elements this set will retain.
  210.      * @return <tt>true</tt> if this collection changed as a result of the
  211.      *         call.
  212.      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
  213.      *           is not supported by this Collection.
  214.      * 
  215.      * @see #remove(Object)
  216.      */
  217.     boolean retainAll(Collection c);
  218.  
  219.  
  220.     /**
  221.      * Removes from this set all of its elements that are contained in the
  222.      * specified collection (optional operation).  If the specified
  223.      * collection is also a set, this operation effectively modifies this
  224.      * set so that its value is the <i>asymmetric set difference</i> of
  225.      * the two sets.
  226.      *
  227.      * @param c collection that defines which elements will be removed from
  228.      *          this set.
  229.      * @return <tt>true</tt> if this set changed as a result of the call.
  230.      * 
  231.      * @throws UnsupportedOperationException if the <tt>removeAll</tt>
  232.      *           method is not supported by this Collection.
  233.      * 
  234.      * @see #remove(Object) */
  235.     boolean removeAll(Collection c);
  236.  
  237.     /**
  238.      * Removes all of the elements from this set (optional operation).
  239.      * This set will be empty after this call returns (unless it throws an
  240.      * exception).
  241.      *
  242.      * @throws UnsupportedOperationException if the <tt>clear</tt> method
  243.      *           is not supported by this set.
  244.      */
  245.     void clear();
  246.  
  247.  
  248.     // Comparison and hashing
  249.  
  250.     /**
  251.      * Compares the specified object with this set for equality.  Returns
  252.      * <tt>true</tt> if the specified object is also a set, the two sets
  253.      * have the same size, and every member of the specified set is
  254.      * contained in this set (or equivalently, every member of this set is
  255.      * contained in the specified set).  This definition ensures that the
  256.      * equals method works properly across different implementations of the
  257.      * set interface.
  258.      *
  259.      * @param o Object to be compared for equality with this set.
  260.      * @return <tt>true</tt> if the specified Object is equal to this set.
  261.      */
  262.     boolean equals(Object o);
  263.  
  264.     /**
  265.      * 
  266.      * Returns the hash code value for this set.  The hash code of a set is
  267.      * defined to be the sum of the hash codes of the elements in the set,
  268.      * where the hashcode of a <tt>null</tt> element is defined to be zero.
  269.      * This ensures that <code>s1.equals(s2)</code> implies that
  270.      * <code>s1.hashCode()==s2.hashCode()</code> for any two sets
  271.      * <code>s1</code> and <code>s2</code>, as required by the general
  272.      * contract of the <tt>Object.hashCode</tt> method.
  273.      *
  274.      * @return the hash code value for this set.
  275.      * @see Object#hashCode()
  276.      * @see Object#equals(Object)
  277.      * @see Set#equals(Object)
  278.      */
  279.     int hashCode();
  280. }
  281.